<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Partial record storage and retrieval</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="am_misc.html" title="Chapter 4.  Access Method Wrapup" />
    <link rel="prev" href="am_misc_bulk.html" title="Retrieving and updating records in bulk" />
    <link rel="next" href="am_misc_struct.html" title="Storing C/C++ structures/objects" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Partial record storage and
        retrieval</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="am_misc_bulk.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 4.  Access Method Wrapup </th>
          <td width="20%" align="right"> <a accesskey="n" href="am_misc_struct.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="am_misc_partial"></a>Partial record storage and
        retrieval</h2>
          </div>
        </div>
      </div>
      <p>
        It is possible to both store and retrieve parts of data
        items in all Berkeley DB access methods. This is done by
        setting the <a href="../api_reference/C/dbt.html#dbt_DB_DBT_PARTIAL" class="olink">DB_DBT_PARTIAL</a> flag <a href="../api_reference/C/dbt.html" class="olink">DBT</a> structure passed to
        the Berkeley DB method.
    </p>
      <p>
        The <a href="../api_reference/C/dbt.html#dbt_DB_DBT_PARTIAL" class="olink">DB_DBT_PARTIAL</a> flag is based on the values of two
        fields of the <a href="../api_reference/C/dbt.html" class="olink">DBT</a> structure: <span class="bold"><strong>dlen</strong></span> 
        and <span class="bold"><strong>doff</strong></span>. The value of <span class="bold"><strong>
        dlen</strong></span> is the number of bytes of the record in
        which the application is interested. The value of <span class="bold"><strong>doff</strong></span> is the offset from the
        beginning of the data item where those bytes start.
    </p>
      <p>
        For example, if the data item were <span class="bold"><strong>
        ABCDEFGHIJKL</strong></span>, a <span class="bold"><strong>doff</strong></span> 
        value of 3 would indicate that the bytes
        of interest started at <span class="bold"><strong>D</strong></span>, and
        a <span class="bold"><strong>dlen</strong></span> value of 4 would
        indicate that the bytes of interest were <span class="bold"><strong>
        DEFG</strong></span>.
    </p>
      <p>
        When retrieving a data item from a database, the <span class="bold"><strong>dlen</strong></span> bytes starting <span class="bold"><strong>doff</strong></span> bytes from the beginning of
        the record are returned, as if they comprised the entire
        record. If any or all of the specified bytes do not exist in
        the record, the retrieval is still successful and any existing
        bytes are returned.
    </p>
      <p>
        When storing a data item into the database, the <span class="bold"><strong>dlen</strong></span> bytes starting <span class="bold"><strong>doff</strong></span> bytes from the beginning of
        the specified key's data record are replaced by the data
        specified by the <span class="bold"><strong>data</strong></span> and
        <span class="bold"><strong>size</strong></span> fields. If <span class="bold"><strong>dlen</strong></span> is smaller than <span class="bold"><strong>size</strong></span>, the record will grow, and if
        <span class="bold"><strong>dlen</strong></span> is larger than
        <span class="bold"><strong>size</strong></span>, the record will
        shrink. If the specified bytes do not exist, the record will
        be extended using nul bytes as necessary, and the store call
        will still succeed.
    </p>
      <p>
        The following are various examples of the put case for the
        <a href="../api_reference/C/dbt.html#dbt_DB_DBT_PARTIAL" class="olink">DB_DBT_PARTIAL</a> flag. In all examples, the initial data item
        is 20 bytes in length: <span class="bold"><strong>ABCDEFGHIJ0123456789</strong></span>
    </p>
      <div class="orderedlist">
        <ol type="1">
          <li>
            <pre class="programlisting">size = 20
doff = 0
dlen = 20
data = abcdefghijabcdefghij

Result: The 20 bytes at offset 0 are replaced by the 20 bytes of 
data; that is, the entire record is replaced.

ABCDEFGHIJ0123456789 -&gt; abcdefghijabcdefghij </pre>
          </li>
          <li>
            <pre class="programlisting">size = 10
doff = 20
dlen = 0
data = abcdefghij

Result: The 0 bytes at offset 20 are replaced by the 10 bytes of 
data; that is, the record is extended by 10 bytes.

ABCDEFGHIJ0123456789 -&gt; ABCDEFGHIJ0123456789abcdefghij </pre>
          </li>
          <li>
            <pre class="programlisting">size = 10
doff = 10
dlen = 5
data = abcdefghij

Result: The 5 bytes at offset 10 are replaced by the 10 bytes of 
data.

ABCDEFGHIJ0123456789 -&gt; ABCDEFGHIJabcdefghij56789 </pre>
          </li>
          <li>
            <pre class="programlisting">size = 10
doff = 10
dlen = 0
data = abcdefghij

Result: The 0 bytes at offset 10 are replaced by the 10 bytes of 
data; that is, 10 bytes are inserted into the record.

ABCDEFGHIJ0123456789 -&gt; ABCDEFGHIJabcdefghij0123456789 </pre>
          </li>
          <li>
            <pre class="programlisting">size = 10
doff = 2
dlen = 15
data = abcdefghij

Result: The 15 bytes at offset 2 are replaced by the 10 bytes of 
data.

ABCDEFGHIJ0123456789 -&gt; ABabcdefghij789 </pre>
          </li>
          <li>
            <pre class="programlisting">size = 10
doff = 0
dlen = 0
data = abcdefghij

Result: The 0 bytes at offset 0 are replaced by the 10 bytes of 
data; that is, the 10 bytes are inserted at the beginning of the 
record.

ABCDEFGHIJ0123456789 -&gt; abcdefghijABCDEFGHIJ0123456789 </pre>
          </li>
          <li>
            <pre class="programlisting">size = 0
doff = 0
dlen = 10
data = ""

Result: The 10 bytes at offset 0 are replaced by the 0 bytes of 
data; that is, the first 10 bytes of the record are discarded.

ABCDEFGHIJ0123456789 -&gt; 0123456789 </pre>
          </li>
          <li>
            <pre class="programlisting">size = 10
doff = 25
dlen = 0
data = abcdefghij

Result: The 0 bytes at offset 25 are replaced by the 10 bytes of 
data; that is, 10 bytes are inserted into the record past the end 
of the current data (\0 represents a nul byte).

ABCDEFGHIJ0123456789 -&gt; ABCDEFGHIJ0123456789\0\0\0\0\0abcdefghij </pre>
          </li>
        </ol>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="am_misc_bulk.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="am_misc.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="am_misc_struct.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Retrieving and updating records in bulk </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Storing C/C++
        structures/objects</td>
        </tr>
      </table>
    </div>
  </body>
</html>
